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Chameleon 


Purpose = I Lis document explains how to use the flash programming utility 
built into the Signum Systems Chameleon Debugger software. 


Installation 


Chameleon Debugger is furnished with a flash programming plug-in. This plug-in is 
installed by default, but can be uninstalled or reinstalled at any time if necessary. For 
details, please refer to Chameleon User Manual. 


Flash Programming Processes 


The process of programming flash using the plug-in programmer consists of two 
phases: 


e configuring (setting the parameters of) the plug-in and 
e executing proper plug-in commands. 
> To program the flash memory on your target system: 


Open the Flash Programmer plug-in dialog by selecting the Flash Programmer 
option from the Tools menu. The Flash Programming dialog box appears 


(Figure 1). 
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Tools Window Help 


: > —== 
i a. CPU & 
Plugins » 
Macros > hucane™ | 


# 6 Flash Programmer > Open 


FIGURE 1 Running the flash programmer. 


Configuring the Plug-In 


Before it can program flash memory, the programmer needs to be configured. The 
first and critical step in setting the necessary programmer parameters is selecting the 
appropriate flash device. 


> To choose the flash device 


1. Choose the flash device programmer and set its parameters in the Flash Device 


tab (Figure 2). 
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Flash Image Flash Device | Utilities | Log | 


Select the flash programmer from the list in Flash Device field or 
specify a custom programmer in the Programmer field. Enter the 
programmer loading RAM address. Some programmers may require 
additional Options. 


Flash Device: [LPC2xnx internal flash programmer Sa | 
Programmer: [D:\SIGNUM \IceFrame\Plugin\Flash\ARMALPC2xxx\LF 7 es 
Base Address: [0x0 >| RAM Address: | =] 


- Erase 
Chip s 
Range © 


Auto @ Provide the flash image file name to use Auto. 
~ Watchdog 


Address: fox8001 _00C0 Value Sequence: fi a) 


~ Startup/Cleanup Macros 


Optionally, specify the name of a subroutine in the startup macro 
preceded by the @ character, or enter the macro file name. 


Startup: 
Cleanup: 


Verbose: 
Options: [pl 14700 
Query Device | 


Save Contig | Close | Help ) 


FIGURE 2 Setting up the flash device and its programmer. 


2. Select the flash device from the Flash Device drop-down list. A programmer 
file associated with the current flash device appears in the Programmer 
drop-down list. Use the Custom option (at the bottom of the Flash Device 
list) to add new devices. 
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3. If you are using a Custom device, select the Programmer file from the 
Programmer drop-down list, or navigate to that file using the browse button 
on the right. 


4. Set the programmer parameters. Refer to your programmer’s documentation 
for a description of the programmer options. 


PARAM- DESCRIPTION 


ETER 

Base The start memory addtess of the flash. 

paltross Passes to the programmer the -b<base_addr> option. 
RAM If the RAM Address field is enabled for editing, enter the 


Aates address of the RAM accessible to the plug-in. The 
minimum amount of memory required is usually specified 
in the Flash Device description. For instance, the “CFI 
16-bit flash programmer (fits 64K RAM).” 


Erase Flash erase control. 


© Chip — erases the entire flash device. 

¢ Range — erases all sectors containing the specified 
range. Eg., to erase one sector at 0x100_0000, the 
range can be set to 0x100_0000-0x100_0000. 
Passes to the programmer the -e<addr>-<addr> 
option. 

¢ Auto — erases all sectors in the address range 
calculated from the image file specified in the 
Image Name text box (Figure 4). 

Watchdog = A sequence of operations of writing to the watchdog 
register that “kicks the dog.” 


e Address — watchdog register address. 

¢ Value Sequence — comma-separated list of values to 
be written to the watchdog register to “kick the 
dog.” Passes to the programmer the 
-w<addr>:<value1>,<addr>:<value2>, ... 
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PARAM- DESCRIPTION 
ETER 
option. 

Startup/ The startup macro prepares the processor for flash 

ae programming. This usually consists in configuring the 

oe flash and RAM memories where the programmer is to be 
loaded, disabling interrupts as well as enabling and 
configuring semi-hosting. The cleanup macro can be used 
to reverse the changes made by the startup macro. A 
subroutine in the target startup macro can be used instead 
of a macro file when preceded by the @ character: 
@yourSubroutineName. 

Verbose Generates extended debugging information from the 
programmer for troubleshooting purposes. Passes to the 
programmer the —v option. 

Options Text field for entering special purpose programmer 


options not found on the Flash Device tab. As of this 
writing, the following options are supported: 


e = f<clk> — System clock frequency. 
"  ccLk in kHz for the Philips LPC2xxx 
programmer. 
" HCLK in MHz for the TI’TMS570 internal 
flash programmer. 
¢ -p<mode> — Flash device dependent option. For: 
" Mitsubishi flash devices used by the CFI 
programmers—-sets the value of the 
protection pin (0 or 1). 
= Philips LPC2,;00/LPC17xx internal flash—If 
<mode> is greater than zero, the 
programmer calculates and programs a valid 
User Program Signature at the reserved 
ARM interrupt vector location (0x14 in 
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LPC2xxx or Ox1C in LPC17 xx). 
e -i<device name> — Forces device identification. Use 
when the device cannot be identified uniquely. 
=" TI TMS470R1 intemal flash programmer— U se 
when the DEV/11...0] register does not 
uniquely identify your device. Example: 
-{TMS470R1A256. 
= ST Microelectronics STR71x intemal flash 
programmer — Used obligatorily. Requires a 
complete part number (-iSTR712FR2T6) or 
flash type code (-i0 stands for 64K flash, -11 
for 128K flash, and —i2 for 256K flash). 
= Philips LPC2;00/LPC17xx internal flash programmer 
— Use when the programmer does not 
recognize the device automatically. Example: 
-iLPC2212 or -1LPC1751. 
=" Analog Devices ADuC70xx intemal flash programmer 
— Use to specify the silicon revision (F to Z). 
Forces the use of the mass-erase flash 
function to erase the entire chip. Without it, 
the chip is erased sector-by-sector. (Note 
that silicon versions earlier than F do not 
support the mass erase functionality.) 


@ -c<mode> — Used to check or calculate parity or 
ECC bits. Available modes: 


= -ceven— even parity bits used. 
= -codd — odd parity bits used. 
=" -cece — ECC code used. 


@ -ma<mask> — Command address mask for the CFI 
programmer. Example: -ma0x7FF 


e@ -md<mask> — Command data mask for the CFI 
programmer. Example: -md0xFF 
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Options for the internal flash F05 in the TI 
TMS470R1x devices—recommended for production 
purposes only. 


-k<key0>,<key1>,<key2>,<key3> — Level 2 security key 
used to unlock the Flash for writing. The key is 
required if the flash has been protected with 
values other then all Fs. If trailing keys are 
omitted, the last specified key is used (at least one 
key is required). Example: 
-k0x11223344,0x55667788 is equal to 
-k0x11223344,0x55667788,0x55667788,0x556677 
88. 


-knew<key0>,<key1>,<key2>,<key3> — New level 2 
security key to be set after programming. Written 
to the device as a new security key. View the Log 
tab to verify the new keys. 


-kcode — New level 2 security key taken from the 
code at address 0x1 FFO-0x1 FFF. 


For example, “-f17400 —p1” in the Options field would 
pass the programmer a clock frequency of 17.4 MHz and 
instruct it to update the code signature at address 0x14. 


Query 
Device 


Button for querying the type of the memory device at the 
base address. 


If a Common Flash Interface (CFI) compliant 
flash device is found, the size of the flash, the 
number and sizes of the sectors, and the 
programmer-recommended name are displayed. 
(The flash log files described in the Flash 
Programming Log section provide more information 
about the device). The Memory Device 
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Information dialog box appears, allowing you to 
set selected parameters to the values returned by 


the query (Figure 3). 


e Ifa non-CFI compliant device or RAM is found, a 
message informing you that ROM or RAM, 
respectively, has been found appears. 


; MENON VEVICENNMONnauT 


> 16-bit Intel/Sharp Extended Command Set flash device at address 0x50000000, 
—/ Device size 0x01000000 (sectors: 128 x Ox20000), 
Manufacturer: Intel (0x89), device ID; 0x18 
Recommended programmer: CFI_be_16.bin 
Recommended programmer options: -ma0x7F 


Detailed information is displayed in the Log tab. 


Do you want to update the Programmer with these parameters? 


Yes No 


FIGURE 3 Flash query using the Query Device button. The results can be used to configure the 
programmer automatically. 


Flash Erasing, Programming and Verification 
> To program the flash, verify the programming, or erase the flash 


1. Set up the flash programming parameters in the Flash Image tab. Choose the 
image file type in the File Type drop-down list box. Then enter the flash 
image file name in the Image Name box, or browse for the file. You may 
need to enter the loading address offset in the Address Offset text box. This 
offset specifies the loading address for binary files or the offset added to the 
loading addresses in HEX, SREC and linker output files. 


2. 


4 — 
Py@eece Flic Prose (%] 


Status: J 


Flash Image | Flash Device | Utilties | Log | 


Flash Device: LPC2xxx internal flash programmer 


File Type: [Linker Output =| 
Image Name: {Support\Philips\Signum-LPC2138\Demo\demoflash.elf v| _... | 
Address Offset: [x0 8 IV Erase Before Programming 

I Verify While Programming 


I Close After Programmming 


Program Verify Erase } 


Save Config Close | Help | 


FIGURE 4 Selecting the flash image parameters and programming operations. 


Program, Verify, Erase or Abort. This step depends on the intended operation. 
Some of these operations may require selecting additional options before 
you press the appropriate operation button. 


Select the Close After Programming option to close the flash programming 
plug-in after successful programming or erasing. 


PROGRAM BUTTON 


Normally, programming the flash device requires earlier erasing the flash 
memory. Also, it is advisable that you verify the contents of the programmed 
flash. These two operations ate controlled by the following options: 


Erase Before Programming Instructs the programmer to erase the entire 
flash memory prior to uploading data to the 
device when the Program button is pressed. 


When uploading multiple files to the flash, 
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deselect Erase Before Programming, and use 
the Erase button to clear the entire flash only 
before programming the first file. 


Verify While Programming Instructs the programmer to perform its own 
programming verification. (This verification 1s 
not to be confused with the verification 
triggered by the Verify button, which 1s 
performed by the flash programming plug-in. 
See the VERIFY BUTTON section further in 
the text.) 


Finally, press the Program button. Flash programming commences and the 
Status text box starts displaying progress report messages. 
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DAMN ash eNOP Nannie [x] 


Status: [Programming at 0x44000 


Flash Image | Flash Device | Utilities | Log | 


Flash Device: AT9S1SAM7Sxx internal flash programmer 


Soll zi 
Image Name: — |D-\Alpha\Debug\4RM\at91 sam7s-ek\atS1 sam7se-ek- al 
Address Offset: fo IV Erase Before Programming 


IV Verify While Programming 


I Close After Programmming 


fei fa Abot | 


Save Config Close | Help | 


FIGURE 5 Programming operation under way. The status is displayed at the top of the dialog 
box. 


VERIFY BUTTON 

The Verify button is used to compare the data in a flash image file with the data 
read from the flash memory. (Please make sure that the Image Name and 
Address Offset are set appropriately before you press the Verify button.) 


Since this verification is performed by the plug-in, and not by the programmer, 
the Flash Device does not need to be specified. Verification performed using the 
Verify button is possible only if the entire flash memory to be verified can be 
read by the plug-in. 


ERASE BUTTON 


This button clears the entire flash memory. Make sure that the currently selected 
flash device is the same as the one used for programming. No other parameter is 
required. 
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ABORT BUTTON 


To terminate the programming, 


verification or erasing operation, press Note: Some flash devices do not allow the 
Aon bolton erase process to be interrupted. 


Utility Functions 


The flash programming plug-in provides two functions frequently used in 
connection with flash programming: Save and Blank Check. To execute these 
functions, select the Utilities tab. 


STapollo:Flash Programming i xi 
Status: | 


Flash Image | Flash Device Utilities | Log | 
Address Range 


From: [ox8000_0000 
To: — [ox8000_1000 


Save... | Blank Check | 


FIGURE 6 The handy Save and Blank Check functions are accessible via the Utilities tab. 


SAVE 


The Save function saves the flash memory within a given address range in a binary 
data file. It is equivalent to the debugger’s SAVE BIN command. Recall that 
debugger commands can be executed in the Chameleon Command window. Since 
the Save function is not limited to flash memory only, you can use it to store 
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memory blocks of any type. The Save function does not depend on any of the 
patameters set in the Flash Image or Flash Device tabs. 


> To save a memory range to a file 


1. Enter the memory range start and end addresses in the From and To text boxes, 
respectively. 


2. Press the Save button. A file open dialog box appears. 


3. Enter the file name, or browse for the binary file, in which the memory range 
data is to be saved. 


BLANK CHECK 
The Blank Check function is used to check if all the bits in the specified memory 


range are set to 1s. As flash memoty is erased by setting its bits to 1s, the function 
verifies that the flash has been erased. The Blank Check function does not depend 
on any of the parameters set in tabs the Flash Image or Flash Device tabs. 

> To verify that a memory range has been erased 


1. Select the desired memory address range in the Address Range group. 


2. Press the Blank Check button. 


Flash Programming Log 
The flash programming plug-in creates a log of flash programming activity. You can 


control the amount and type of information stored, save, copy and clear the log 
using the controls found in the Log tab. 
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STapollo:Flash Programming xi 
Status: [Programming completed. 


Flash Image | Flash Device | Utilities Log | 


Programming ... 


- programmer: "D:\Signum'\ IceFrame\ Plugin) Flash) ARM\¢ 
- address offset: Oxs000b000 
- image name: "D:\ Alpha) STMicro\smalli0d0.bin" 


- requested erasing before programming 

- requested verification after programming 

STapollo: Erasing the flash... 

STapollo: Block O size Oxi00. 

STapollo: Block O addr Oxs000b000. 

STapollo: Data offset=0x0 length=0x100. 

STapollo: Programming a block at Ox8000b000 Ox1i100 bytes. 
STapollo: Verifying at Ox8000b000 a block of Ox40 dword: 
Programming completed. 
Time elapsed: 


» 


Log Level: [User's Log Fa 
Save... | Copy To Clipboard | Clear | 


FIGURE7 The flash programming log window. 


LOG LEVEL 


The log content can be filtered in several ways. Use the Log Level drop-down list to 
select the filtering criteria that fit your needs best. The available levels are listed below 
in increasing order of comprehensiveness. 


Errors Only The log records only error messages. 
Normal In addition to Errors Only level messages, the log records 


commands (Erase, Program, Save, Bank Check, etc.) along with 
their parameters. 
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User's Log In addition to Normal level messages, the log records messages 
from the programmer execution on the target board. The 
programmet’s messages ate prefixed by the target name. For 
example, a message from the STapollo target may look like this: 
“STapollo: Erasing the flash .. .” 


Calls Except Data Access In addition to User’s Log level messages, the log records 
requests from the programmer code to the flash programming plug- 
in, with the exception of those relating to flash image data. 


All Calls In addition to Calls Except Data Access level messages, the log 
records those requests from the programmer to the plug-in that 
relate to the flash image. 


All Calls and Data In addition to All Calls level messages, the log records the flash 
image data passed from the plug-in to the programmer. 


The Normal log level is designed to help you keep track of the performed operation, 
allowing you to verify the data used to program the flash, destination addresses, and 
the like. 

The Uset’s Log and higher levels are designed to troubleshoot the programming 


process or debug the programmer code. These levels degrade programming 
performance considerably, and therefore are not recommended to be used routinely. 


SAVE 
> To save the current log 
1. Click the Save button. The Save As dialog appears. 


2. Enter the name of the log file, or browse for the existing file. 


3. Press OK to save the log to the file. 
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COPY TO CLIPBOARD 


The Copy To Clipboard button copies the entire current log to the MS Windows 
clipboard. 


CLEAR 


The Clear button erases the current log from the flash programming log window. 


Flash Programming using Macros 


Setting Plug-In Parameters for Flash Programming with Macros 

Perhaps the easiest way to create a macro that configures the plug-in is to set the 
parameters via the plug-in GUI interface, as described earlier in the Configuring the 
Plug-In section, and then to save the configuration commands to a file by pressing the 
Save Config button (Figure 2). 


Plug-in Configuration Macrofile Example 


lugin paramset FlashImage.EraseBeforeProgramming=1 
lugin paramset FlashImage.VerifyWhileProgramming=1 
lugin paramset FlashImage.AddressOffset=0 

lugin paramset FlashImage.FileType=0 

lugin paramset 
lashImage. ImageName="D: \Alpha\AT91EB40A\Flash\demo.elf" 
lugin paramset FlashDevice.FlashDevice="LPC2xxx internal 
lash programmer" 

lugin paramset 

lashDevice. Programmer="D:\Chameleon\Plugin\Flash\ARM\LPC2xx 
\LPC2xxx.elf" 

lugin paramset FlashDevice.StartupMacro="D:\ Chameleon 
Arm\TestFlashStartup.mac" 
lugin paramset FlashDevice.CleanupMacro="D:\ Chameleon 
Arm\TestFlashCleanup.mac" 

lugin paramset FlashDevice.Options="-£17400" 

lugin paramset FlashDevice.BaseAddress="0x100_0000" 
lugin paramset FlashDevice.Erase.From="0x100_0000" 
lugin paramset FlashDevice.Erase.To="0x11F_FFFF" 


eal teah Meal lea) 


O'O'S' <—'0 —'O K H'O M'O W'0 19 1010'S 
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lashDevice.Watchdog.Address="0x8001_00C0" 
lashDevice.Watchdog.ValueSequence="1,0" 
lashDevice.Verbose=1 
lashDevice.Erase.Chip=0 


lugin paramset 
lugin paramset 
lugin paramset 
lugin paramset 
lugin paramset FlashDevice.Erase.Range=1 

lugin paramset Utilities.AddressRange.From=0x0100_0000 
lugin paramset Utilities.AddressRange.To=0x011F_FFFF 
lugin paramset 
tilities.Save.FileName="D:\Alpha\EB40A\EB40A.bin" 
lugin paramset Log.Loglevel=1 


ie 
et 
ie 
le 
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For added flexibility, absolute file pathnames may be converted into relative paths 
with the use of the $ character. The plug-in treats the $ as representing the path to 
the debugger installation directory. Thus, for example, it is possible to use in a macro 
file statements like this: 


lugin paramset 

lashDevice. StartupMacro="$\Arm\TestFlashStartup.mac" 
lugin paramset 
lashDevice.CleanupMacro="$\Arm\TestFlashCleanup.mac" 


T'S "W'S 


Plug-In Commands for Flash Programming with Macros 


In a macro file, all plug-in programmer commands—PROGRAM, ERASE and 
VERIFY—nmust be preceded by the keyword “flash,” for example: 


flash program 
flash erase 


Plug-in programmer commands ate case-insensitive. 


Putting it Together 


Commands that configure the programmer and commands operating on flash 
memory can be combined together to fully automate the process of flash 
programming. An example of a complete macro file that first erases and then 
programs flash is shown below. 


; flash.mac - program my demo program into the flash 
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lugin paramset FlashDevice.FlashDevice="LPC2xxx internal 
lash programmer" 

lugin paramset 

lashDevice. Programmer="D: \Chameleon\Plugin\Flash\ARM\LPC2xx 
\LPC2xxx.elf" 

lugin paramset FlashDevice.StartupMacro=" " 

lugin paramset FlashDevice.CleanupMacro=" " 

lugin paramset FlashDevice.BaseAddress="0x100_0000" 

lugin paramset FlashDevice.Erase.Chip=1 


th 'O'O'O'S & AI'd Md 


lash erase 


lugin paramset FlashImage.EraseBeforeProgramming=0 
lugin paramset FlashImage.VerifyWhileProgramming=0 
lugin paramset FlashImage.FileType=0 ; O-linker file, 1 
EX, 2-binary, 3-SREC 
lugin paramset 
lashImage.ImageName="D: \Alpha\AT91EB40A\Flash\demo.elf" 
lugin paramset FlashImage.AddressOffset=0 


Pict ee oe 


lash program 
lash verify 


; End of flash.mac 
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Appendix 


Using the flash programmer with selected evaluation boards 


Sharp KEV75401 Evaluation Board 
This target board is equipped with the LH28F320BFE flash device. 


> To enable the board for flash programming, set the jumpers as follows: 


JUMPER SETTING FUNCTION 


JP19 Opened Flash boot block not protected 
JP20 Opened Bus width 16 bit 
JP27 Closed Flash write protection disabled 


> To select a flash memory address, set the jumpers as follows: 


JUMPER SETTING FUNCTION 


JP21 2-3 Flash is selected by CSO and 
jp22 1-2 located at address 0x40000000. 
JP21 1-2 Flash is selected by CS1 and 
jp22 223 located at address 0x44000000. 


e When the flash is selected by CSO, select the “Sharp KEV75401 with the 
LH28F320BFE flash with CSO” programmer in the Flash Device tab. See 
the Configuring the Plug-In section.) 


e Otherwise, select “Sharp KEV75401 with the LH28F320BFE flash with 
Csi” 


> To refine flash programming, set the following Options in the Flash Device tab 
(Figure 2): 
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OPTION SYNTAX FUNCTION 
-b<flash-base-address> Sets the flash base address 


-e<start_addr>[-<end_addr>] —_ Erases the sectors in the 
specified address range 


-V ‘Turns the verbose mode on 
for troubleshooting 
purposes 


For example, 
-b0x4000_0000 -e0x4000_0000-0x4000_FFFF -v 


defines the flash base address as 0x4000_0000, instructs the programmer to 
erase the flash memory between address 0x4000_0000 through 0x4000_FFFF, 
and enables the verbose mode of the programmer. 


) 
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